Token

Create a new webhook [Beta]

Create a new webhook for a given chain. The webhook will receive real-time token scan updates.

Webhook Endpoint Requirements

To ensure proper functionality, your webhook endpoint must meet the following requirements:

✅ Response Criteria

Must return an HTTP 200 OK status code upon successful receipt.
Must respond within 1 second.
If the endpoint is unreachable for more than 1 hour, the webhook will be automatically disabled.

🔄 Synchronization Process

Subscribe to the webhook to start receiving updates.
Receive real-time updates for new token scans

Webhook Request Format

The webhook will send POST requests containing an array of token scan results:

List[TokenValidationResponse]

For detailed response structure, see the Token Scan Response Reference.

Note

The same token will have multiple scan results over time
Ensure that your system properly handles state overrides to reflect the most up-to-date token status.

POST

token

hooks

{chain}

Create a new webhook [Beta]

curl --request POST \
  --url https://api.blockaid.io/v0/token/hooks/{chain} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "https://example.com/",
  "shared_secret_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "filter": {
    "filter_type": "token_address",
    "token_addresses": [
      "0x1234567890abcdef1234567890abcdef12345678"
    ]
  }
}
'

{
  "url": "<string>",
  "shared_secret_key": "<string>",
  "chain": "arbitrum",
  "active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key

string

header

required

Path Parameters

chain

enum<string>

required

The chain name

Available options:

arbitrum,

avalanche,

base,

bsc,

ethereum,

optimism,

polygon,

zora,

solana,

starknet,

starknet-sepolia,

stellar,

linea,

degen,

zksync,

scroll,

blast,

soneium-minato,

base-sepolia,

bitcoin,

abstract,

soneium,

ink,

zero-network,

berachain,

unichain,

ronin,

sui,

hedera

Body

application/json

url

string<uri>

required

Minimum length: 1

shared_secret_key

string | null

Optional shared secret key (32 characters), used to calculate the HMAC signature

filter

object | null

Filter for webhook updates

TokenAddressFilter
TokenTypeFilter

Show child attributes

Response

Successful Response

url

string<uri>

required

Minimum length: 1

chain

enum<string>

required

The chain name

Available options:

arbitrum,

avalanche,

base,

bsc,

ethereum,

optimism,

polygon,

zora,

solana,

starknet,

starknet-sepolia,

stellar,

linea,

degen,

zksync,

scroll,

blast,

soneium-minato,

base-sepolia,

bitcoin,

abstract,

soneium,

ink,

zero-network,

berachain,

unichain,

ronin,

sui,

hedera

active

boolean

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

shared_secret_key

string | null

Optional shared secret key (32 characters), used to calculate the HMAC signature

Delete a webhookDelete an existing webhook subscription for a given chain. This will immediately stop sending token scan updates to the webhook URL. Returns a 204 status code on successful deletion.

⌘I

Create a new webhook [Beta]

curl --request POST \
  --url https://api.blockaid.io/v0/token/hooks/{chain} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "https://example.com/",
  "shared_secret_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "filter": {
    "filter_type": "token_address",
    "token_addresses": [
      "0x1234567890abcdef1234567890abcdef12345678"
    ]
  }
}
'

{
  "url": "<string>",
  "shared_secret_key": "<string>",
  "chain": "arbitrum",
  "active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Get Started

Enums

Blockaid

Essentials

Create a new webhook [Beta]

Webhook Endpoint Requirements

✅ Response Criteria

🔄 Synchronization Process

Webhook Request Format

Note

Authorizations

Path Parameters

Body

Response